feat: add an AI page#821
Conversation
Signed-off-by: Henry Schreiner <henryfs@princeton.edu>
Added tips for using AgentsView and Claude Code.
Signed-off-by: Henry Schreiner <henryfs@princeton.edu>
Co-authored-by: Eric Ma <ericmjl@users.noreply.github.com>
ericmjl
left a comment
ericmjl
left a comment
There was a problem hiding this comment.
In general, really loving the policy! So many things resonate. I will be doing a series of blog posts on the weekend about scipy, including commentating on my thoughts on the use of AI in open source, and I think referencing this PR is going to be part of the story!
Co-authored-by: Eric Ma <ericmjl@users.noreply.github.com> Co-authored-by: Lundy Bernard <lundybernard@users.noreply.github.com>
| You can also mention `@AGENTS.md` inside `CLAUDE.md` if you want to add | ||
| specific instructions; this is true for all the other harnesses too | ||
| (`copilot-instructions.md`, etc). |
There was a problem hiding this comment.
the @file-name.md is a special feature of ClaudeCode. Like a template, it injects the full text of the target file into context... yet the ClaudeCode best practices shows the example "See @README.md for project overview and @package.json for available npm commands." which would create a garbled mess...
Its nice that this makes CLAUDE.md composable, but its not a standard.
I think the wording is a little misleading here, because @file-injection is not true for all harnesses.
| You can also mention `@AGENTS.md` inside `CLAUDE.md` if you want to add | |
| specific instructions; this is true for all the other harnesses too | |
| (`copilot-instructions.md`, etc). | |
| You can also mention `@AGENTS.md` inside `CLAUDE.md` which injects the text form the @/path/to/file.md into CLAUDE.md when ClaudeCode reads it. You can include ClaudeCode specific instructions, and inject text from any other .md file you wish `copilot-instructions.md` for example. |
There was a problem hiding this comment.
"All" is incorrect, but most of them do have this feature - I think every single one I've tried (OpenCode, Pi, Codex, Copilot). If it's not part of the agent, most models should realize you are referring to a file and try to read it anyway. Also, it doesn't inject, it reads and sends a structured message. So it's perfectly fine to add in inside a sentence. It will also know what file it referenced.
There was a problem hiding this comment.
It's wrong about copilot below, that's also @, that's where I first used it. Probably confusing another of Microsoft's 75 tools named copilot.
"eager" means it reads the file and sends it along as text, vs. attaching the file and giving the model options about reading it.
🤖 AI text below 🤖
| Tool | Syntax | Notes |
|---|---|---|
| Claude Code | @file | Eager, full-file inline |
| pi | @file | Eager; works in TUI and on command line |
| Cursor | @Files (+ @Folders, @code, @git, @docs, @codebase) | The tool that popularized this; richest taxonomy |
| Windsurf (Cascade) | @file (+ @function, @docs) | Explicitly modeled on Cursor |
| Cline | @/path (+ @problems, @Terminal, @git, @url) | Eager, full-file |
| Gemini CLI | @file | Eager, client-side injection |
| opencode | @file (+ @alias references) | On-demand read |
| Codex | @file / /mention | Attaches to context; completeness less guaranteed |
| Copilot | #file | @ reserved for participants (@workspace) |
| Aider | /add (slash command) | Different paradigm entirely |
There was a problem hiding this comment.
very cool, last I checked (more than 15 minutes ago) it was just a ClaudeCode thing, sounds like its becoming standard(ish) in AGENTS.md-type-files
|
|
||
| Commit `AGENTS.md` so every contributor (and their harness) shares the same | ||
| project context. This is a good default for projects with at least one | ||
| maintainer also using AI harnesses. (Ignoring `CLAUDE.md` and `.claude/` in your `.gitignore` is |
There was a problem hiding this comment.
CLAUDE.local.md should also always be ignored and never committed. It is designed for per-user personal settings.
Projects that wish to totally exclude CLAUDE.md could direct users to just @AGENTS.md in their CLAUDE.local.md as a good practice.
There was a problem hiding this comment.
I didn't know about that one!
|
Something for the tips section, or a separate Patterns article we could reference from this one. I would recommend people add Architecture Design Records (ADRs) to projects where they use or support the use of Ai. They make explicit, design decisions that are often invisible or obscure in the code its self, and are beneficial to human contributors even in a world without Ai. Recommending from personal experience, I've seen major improvements in agent behavior using this strategy. I had Fable dig up some papers, review my own setup, and write this argument for their use with citations: 🤖 AI text below 🤖 There's early quantitative support that decision-record-style context is the kind that actually helps agents. A controlled study found agents complied with project decisions 46% of the time from code alone vs. 95% when decision records were retrievable — with the gap concentrated in decisions that aren't visible in the code arXiv:2605.08112. On SWE-bench Verified, tuned repository guidance lifted resolve rates from 25.5% to 33.0% (p<0.001), and the useful content was largely structural/architectural knowledge arXiv:2606.20512. Notably, a null-result study on AGENTS.md files found generic repo overviews don't help — but prescriptive instructions are followed arXiv:2602.11988. ADRs land on the right side of that split: decisions and constraints, not prose summaries. |
4 participants
Fix #807.
This adds an AI page. Fitting to the theme, it was started by pointing Claude Opus at the issue and then reworked and added to (original output available in a comment on that issue).
There still are some things left to do:
AI_POLICY.mdprobably needs a proper human-written version for all three examples.AGENTS.md. I'd be biased toward not providing an AGENTS.md, but looking at the generated AGENTS.md and making sure it covers everything; anything it's missing we could add to the exisiting contribution guide, which should then show up in the AGENTS.md. But open to playing with this and other options.AI_POLICY.md, at least yet, and let projects select and modify their own.I'll also leave this open for a bit for reviews and suggestions.
📚 Documentation preview 📚: https://scientific-python-cookie--821.org.readthedocs.build/